PunchOut Integration

PunchOut Overview

Adaptive Catalog supports both the cXML PunchOut protocol as well as a more modern JSON based PunchOut. These systems allow users to seamlessly navigate from their quoting tool, CRM, or any other system to Adaptive Catalog to find products, and return with the full product details.

cXML PunchOut Process

Step 1: PunchOutSetupRequest

Call https://api.adaptivecatalog.com/api/punchout/setup/xml with the following request:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.040/cXML.dtd">
<cXML payloadID="1539050765.0492@example.com" timestamp="2018-10-09T02:06:05+00:00">
  <Header>
    <From>
      <Credential domain="NetworkId">
        <Identity>user@example.com</Identity>
      </Credential>
    </From>
    <To>
      <Credential domain="NetworkId">
        <Identity>user@example.com</Identity>
      </Credential>
    </To>
    <Sender>
      <Credential domain="NetworkId">
        <Identity>{USER EMAIL}</Identity>
        <SharedSecret>{API KEY}</SharedSecret>
      </Credential>
      <UserAgent>Application Name v1.2.3</UserAgent>
    </Sender>
  </Header>
  <Request deploymentMode="production">
    <PunchOutSetupRequest operation="create">
      <BuyerCookie>550bce3e592023b2e7b015307f965133</BuyerCookie>
      <BrowserFormPost>
        <URL>{YOUR POST URL}</URL>
      </BrowserFormPost>
    </PunchOutSetupRequest>
  </Request>
</cXML>

The only fields that Adaptive Catalog will currently read are

Header.Sender.Credential.Identity	The Adaptive Catalog user email address
Header.Sender.Credential.SharedSecret	The Adaptive Catalog API Key
Request.PunchoutSetupRequest.BrowserFormPost.URL	The URL to send the cXML response to upon submission
Header.From.Credential.Domain	Returned with the PunchOutOrderMessage. Can be any string value.
Header.From.Credential.Identity	Returned with the PunchOutOrderMessage. Can be any string value. Generally a username / email.

Step 2: PunchOutSetupResponse

Upon successful validation of the API key and username, Adaptive Catalog will return a cXML PunchOutSetupResponse. You should then direct your users to the Response.Status.PunchOutSetupResponse.StartPage.URL to create their bill of materials.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.040/cXML.dtd">
<cXML payloadID="1539050765.83749@example.com" timestamp="2018-04-07T16:16:53-05:00">
  <Response>
    <Status code="200" text="OK"></Status>
      <PunchOutSetupResponse>
        <StartPage>
          <URL>https://app.adaptivecatalog.com/punchout?sessionKey={SESSIONKEY}</URL>
        </StartPage>
      </PunchOutSetupResponse>
  </Response>
</cXML>

Step 3: User Creates Workspace

Inside of Adaptive Catalog, the user will either create a new workspace and assemble the bill of materials, or select an existing workspace. Once ready, they will click the Submit button to proceed.

Step 4: PunchOutOrderMessage

<?xml version="1.0" encoding="UTF-8"?>
<cXML version="1.1" payloadID="2011-04-06T13:15:06.12349832.13284838@dell.com" timestamp="2011-04-06T13:15:06">
   <Header>
      <From>
         <Credential domain="DUNS">
            <Identity>128293714</Identity>
         </Credential>
      </From>
      <To>
         <Credential domain="NetworkId">
            <Identity>YOURIDENTITY</Identity>
         </Credential>
      </To>
      <Sender>
         <Credential domain="DUNS">
            <Identity>128293714</Identity>
            <SharedSecret>nopassword</SharedSecret>
         </Credential>
         <UserAgent>Dell cXML V1.1</UserAgent>
      </Sender>
   </Header>
   <Message deploymentMode="test">
      <PunchOutOrderMessage>
         <PunchOutOrderMessageHeader operationAllowed="edit">
            <Total>
               <Money currency="USD">1453.00</Money>
            </Total>
         </PunchOutOrderMessageHeader>
         <ItemIn quantity="1">
            <ItemID>
               <SupplierPartID>223-4511</SupplierPartID>
               <SupplierPartAuxiliaryID>1006910622287\1</SupplierPartAuxiliaryID>
            </ItemID>
            <ItemDetail>
               <UnitPrice>
                  <Money currency="USD">1453.00</Money>
               </UnitPrice>
               <Description xml:lang="en">OptiPlex 755 Energy Smart Minitower</Description>
               <UnitOfMeasure>EA</UnitOfMeasure>
               <Classification domain="UNSPSC">43211507</Classification>
               <ManufacturerPartID>223-4511</ManufacturerPartID>
               <ManufacturerName>Dell</ManufacturerName>
               <Extrinsic name="Image">{URL}</Extrinsic>
               <Extrinsic name="Notes">These are item notes</Extrinsic>
            </ItemDetail>
         </ItemIn>
                 <ItemIn quantity="1">
            <ItemID>
               <SupplierPartID>32023</SupplierPartID>
               <SupplierPartAuxiliaryID>392002</SupplierPartAuxiliaryID>
            </ItemID>
            <ItemDetail>
               <UnitPrice>
                  <Money currency="USD">894.00</Money>
               </UnitPrice>
               <Description xml:lang="en">Dell UltraSharp 4K 27" Display</Description>
               <UnitOfMeasure>EA</UnitOfMeasure>
               <Classification domain="UNSPSC">43211507</Classification>
               <ManufacturerPartID>303002</ManufacturerPartID>
               <ManufacturerName>Dell</ManufacturerName>
               <Extrinsic name="Image">{URL}</Extrinsic>
               <Extrinsic name="Notes">These are item notes</Extrinsic>
            </ItemDetail>
         </ItemIn>
      </PunchOutOrderMessage>
   </Message>
</cXML>

A list of extrinsic fields currently included are:

Field	Description
Image	A URL to the product image
Notes	HTML encoded product description

JSON PunchOut Process

While the procedure for the JSON PunchOut process is nearly identical, the calls are slightly different and more information is provided.

Step 1: Call the JSON PunchOut Endpoint

First call the JSON PunchOut endpoint with the following information:

{
    "company": "{USER'S COMPANY NAME}",
    "username": "{USER'S ADAPTIVE CATALOG USERNAME}",
    "apiKey": "{USER'S API KEY}",
    "callbackUrl": "{URL FOR YOUR CALLBACK ENDPOINT}"
}

If the API Key, username, and company all match, Adaptive Catalog will respond with the redirect URL including a session key.

{
    "url": "{URL}"
}

Step 2: User Creates Workspace

Inside of Adaptive Catalog, the user will either create a new workspace and assemble the bill of materials, or select an existing workspace. Once ready, they will click the Submit button to proceed.

Step 3: PunchOut Callback

The user will be directed to POST the following JSON to the provided Callback URL

{
  "items": [
    {
      "id": "{WORKSPACE ITEM ID}",
      "productId": "{ADAPTIVE CATALOG PRODUCT ID}",
      "catalog": "{THE CATALOG NAME THAT CONTAINS THE PRODUCT}",
      "workspace": "{THE NAME OF THE WORKSPACE}",
      "product": {
        "id": "{ADAPTIVE CATALOG PRODUCT ID}",
        "description": "{FULL PRODUCT DESCRIPTION IN HTML}",
        "manufacturer": "{PRODUCT MANUFACTURER}",
        "manufacturerPartNumber": "{PRODUCT MFP}",
        "msrp": 0.0,
        "name": "{PRODUCT NAME}",
        "image": "{URL TO PRODUCT IMAGE}",
        "catalog": "{THE CATALOG NAME THAT CONTAINS THE PRODUCT}",
        "unspsc": "{THE PRODUCT UNSPSC}",
        "vendors": [
          {
            "cost": 0.0,
            "onHand": 0.0,
            "inStock": false,
            "vendorPartNumber": "value",
            "vendorName": "value"
          }
        ],
        "attributes": {
          "key1": "value1",
          "key2": "value2",
          "key3": "value3"
        },
        "facets": {
          "key1": "value1",
          "key2": "value2",
          "key3": "value3"
        },
        "filters": {
          "key1": 0.0,
          "key2": 0.0,
          "key3": 0.0
        },
        "links": [
          {
            "type": "{ACCESSORY, UPSELL, SERVICE}",
            "value": "{PRODUCT ID}",
            "recommended": false
          }
        ],
        "segment": "{HIGH LEVEL PRODUCT CATEGORY}",
        "category": "{PRODUCT CATEGORY}",
        "subCategory": "{PRODUCT SUB-CATEGORY}",
        "favorite": {
          "company": false,
          "user": false
        }
      },
      "details": {
        "quantity": 0.0,
        "price": 0.0
      }
    }
  ]
}